<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>Securing Enterprise Beans - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level2"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<div class="onpage">
<p class="toc level3"><a href="">Securing Enterprise Beans</a></p>
<p class="toc level4"><a href="#bnbyn">Accessing an Enterprise Bean Caller's Security Context</a></p>
<p class="toc level4"><a href="#bnbyo">Declaring Security Role Names Referenced from Enterprise Bean Code</a></p>
<p class="toc level5"><a href="#bnbyp">Declaring Security Roles Using Annotations</a></p>
<p class="toc level5"><a href="#bnbyq">Declaring Security Roles Using Deployment Descriptor Elements</a></p>
<p class="toc level4 tocsp"><a href="#bnbyr">Defining a Security View of Enterprise Beans</a></p>
<p class="toc level5"><a href="#bnbys">Defining Security Roles</a></p>
<p class="toc level5"><a href="#bnbyu">Specifying an Authentication Mechanism</a></p>
<p class="toc level5"><a href="#bnbyv">Specifying Method Permissions</a></p>
<p class="toc level5"><a href="#bnbyy">Mapping Security Roles to Application Server Groups</a></p>
<p class="toc level5"><a href="#bnbyz">Propagating Security Identity</a></p>
<p class="toc level4 tocsp"><a href="#bnbzd">Using Enterprise Bean Security Annotations</a></p>
<p class="toc level4"><a href="#bnbze">Using Enterprise Bean Security Deployment Descriptor Elements</a></p>
<p class="toc level4"><a href="#bnbzf">Configuring IOR Security</a></p>
<p class="toc level4"><a href="#bnbzg">Deploying Secure Enterprise Beans</a></p>
<p class="toc level5"><a href="#bnbzh">Accepting Unauthenticated Users</a></p>
<p class="toc level5"><a href="#bnbzi">Accessing Unprotected Enterprise Beans</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnbzj.html">Enterprise Bean Example Applications</a></p>
<p class="toc level4"><a href="bnbzj.html#bnbzk">Example: Securing an Enterprise Bean</a></p>
<p class="toc level5"><a href="bnbzj.html#bnbzl">Annotating the Bean</a></p>
<p class="toc level5"><a href="bnbzj.html#bnbzm">Setting Runtime Properties</a></p>
<p class="toc level5"><a href="bnbzj.html#bnbzn">Building, Deploying, and Running the Secure Cart Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbzj.html#bnbzo">Building, Deploying, and Running the Secure Cart Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbzj.html#bncaa">Example: Using the <tt>isCallerInRole</tt> and <tt>getCallerPrincipal</tt> Methods</a></p>
<p class="toc level5"><a href="bnbzj.html#bncab">Modifying <tt>ConverterBean</tt></a></p>
<p class="toc level5"><a href="bnbzj.html#bncac">Modifying Runtime Properties for the Secure Converter Example</a></p>
<p class="toc level5"><a href="bnbzj.html#bncad">Building, Deploying, and Running the Secure Converter Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbzj.html#bncae">Building, Deploying, and Running the Secure Converter Example Using Ant</a></p>
<p class="toc level5"><a href="bnbzj.html#bncaf">Troubleshooting the Secure Converter Application</a></p>
<p class="toc level4 tocsp"><a href="bnbzj.html#bncag">Discussion: Securing the Duke's Bank Example</a></p>
<p class="toc level3 tocsp"><a href="bncah.html">Securing Application Clients</a></p>
<p class="toc level4"><a href="bncah.html#bncai">Using Login Modules</a></p>
<p class="toc level4"><a href="bncah.html#bncaj">Using Programmatic Login</a></p>
<p class="toc level3 tocsp"><a href="bncal.html">Securing EIS Applications</a></p>
<p class="toc level4"><a href="bncal.html#bncam">Container-Managed Sign-On</a></p>
<p class="toc level4"><a href="bncal.html#bncan">Component-Managed Sign-On</a></p>
<p class="toc level4"><a href="bncal.html#bncao">Configuring Resource Adapter Security</a></p>
<p class="toc level4"><a href="bncal.html#bncap">Mapping an Application Principal to EIS Principals</a></p>
<p class="toc level2 tocsp"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnbyk.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnbzj.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnbyl"></a><h3>Securing Enterprise Beans</h3>
<a name="indexterm-2579"></a><a name="indexterm-2580"></a><a name="indexterm-2581"></a><a name="indexterm-2582"></a><a name="indexterm-2583"></a><p>Enterprise beans are the Java EE components that implement Enterprise JavaBeans (EJB) technology.
Enterprise beans run in the EJB container, a runtime environment within the Application
Server, as shown in <a href="#bnbym">Figure&nbsp;29-1</a>.</p><a name="bnbym"></a><h6>Figure&nbsp;29-1 Java EE Server and Containers</h6><img src="figures/overview-serverAndContainers.gif" alt="Diagram of Java EE server showing web container and EJB container"></img><p>Although transparent to the application developer, the EJB container provides system-level services such
as transactions and security to its enterprise beans. These services enable you to
quickly build and deploy enterprise beans, which form the core of transactional Java
EE applications.</p><p>The following sections describe declarative and programmatic security mechanisms that can be used
to        protect enterprise bean resources.
The protected resources include methods of enterprise beans that are called from application clients,
web components, or other enterprise beans. This section assumes that you have read
<a href="bnbls.html">Chapter&nbsp;20, Enterprise Beans</a> and <a href="bnbnb.html">Chapter&nbsp;21, Getting Started with Enterprise Beans</a> before starting this section.</p><p>You can protect enterprise beans by doing the following:</p>
<ul><li><p><a href="#bnbyn">Accessing an Enterprise Bean Caller's Security Context</a></p></li>
<li><p><a href="#bnbyo">Declaring Security Role Names Referenced from Enterprise Bean Code</a></p></li>
<li><p><a href="#bnbyr">Defining a Security View of Enterprise Beans</a></p></li>
<li><p><a href="#bnbzd">Using Enterprise Bean Security Annotations</a></p></li>
<li><p><a href="#bnbze">Using Enterprise Bean Security Deployment Descriptor Elements</a></p></li>
<li><p><a href="#bnbzf">Configuring IOR Security</a></p></li>
<li><p><a href="#bnbzg">Deploying Secure Enterprise Beans</a></p></li></ul>
<p>Two example applications demonstrate adding security to enterprise beans. These example applications are
discussed in the following sections:</p>
<ul><li><p><a href="bnbzj.html#bnbzk">Example: Securing an Enterprise Bean</a></p></li>
<li><p><a href="bnbzj.html#bncaa">Example: Using the <tt>isCallerInRole</tt> and <tt>getCallerPrincipal</tt> Methods</a></p></li></ul>
<p>You should also read <i>JSR-220: Enterprise JavaBeans 3.0</i> for more information on this topic. This document
can be downloaded from <a href="http://jcp.org/en/jsr/detail?id=220">http://jcp.org/en/jsr/detail?id=220</a>. Chapter 16 of this specification, <i>Security Management</i>, discusses security management
for enterprise beans.</p>

<a name="bnbyn"></a><h4>Accessing an Enterprise Bean Caller&rsquo;s Security Context</h4>
<p>In general, security management should be enforced by the container in a manner
that is transparent to the enterprise beans&rsquo; business methods. The security API described
in this section should be used only in the less frequent situations in
which the enterprise bean business methods need to access the security context information.</p><p>The <tt>javax.ejb.EJBContext</tt> interface provides two methods that allow the bean provider to access
security information about the enterprise bean&rsquo;s caller.</p>
<ul><li><p><a name="indexterm-2584"></a><tt>java.security.Principal getCallerPrincipal();</tt></p><p>The purpose of the <tt>getCallerPrincipal</tt> method is to allow the enterprise bean methods to obtain the current caller principal&rsquo;s name. The methods might, for example, use the name as a key to information in a database.</p></li>
<li><p><a name="indexterm-2585"></a><tt>boolean isCallerInRole(String roleName);</tt></p><p>The purpose of the <tt>isCallerInRole(String roleName)</tt> method is to test whether the current caller has been assigned to a given security role. Security roles are defined by the bean provider or the application assembler, and are assigned to principals or principals groups that exist in the operational environment by the deployer.</p></li></ul>
<p>The following code sample illustrates the use of the <tt>getCallerPrincipal()</tt> method:</p><pre>@Stateless public class EmployeeServiceBean
         implements EmployeeService{
    @Resource SessionContext ctx;
    @PersistenceContext EntityManager em;

    public void changePhoneNumber(...) {
        ...
        // obtain the caller principal.
        callerPrincipal = ctx.getCallerPrincipal();

        // obtain the caller principal&rsquo;s name.
        callerKey = callerPrincipal.getName();

        // use callerKey as primary key to find EmployeeRecord
        EmployeeRecord myEmployeeRecord =
            em.findByPrimaryKey(EmployeeRecord.class, callerKey);

        // update phone number
        myEmployeeRecord.setPhoneNumber(...);

        ...
    }
}</pre><p>In the previous example, the enterprise bean obtains the principal name of the
current caller and uses it as the primary key to locate an
<tt>EmployeeRecord</tt> entity. This example assumes that application has been deployed such that the
current caller principal contains the primary key used for the identification of employees
(for example, employee number).</p><p>The following code sample illustrates the use of the <tt>isCallerInRole(String roleName)</tt> method:</p><pre>@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll {
     @Resource SessionContext ctx;

     public void updateEmployeeInfo(EmplInfo info) {

         oldInfo = ... read from database;

         // The salary field can be changed only by callers
         // who have the security role "payroll"
         if (info.salary != oldInfo.salary &amp;&amp;
             !ctx.isCallerInRole("payroll")) {
                 throw new SecurityException(...);
         }
         ...
     }
     ...
 }</pre><p>An example application that uses the <tt>getCallerPrincipal</tt> and <tt>isCallerInRole</tt> methods is described
in <a href="bnbzj.html#bncaa">Example: Using the <tt>isCallerInRole</tt> and <tt>getCallerPrincipal</tt> Methods</a>.</p>

<a name="bnbyo"></a><h4>Declaring Security Role Names Referenced from Enterprise Bean Code</h4>
<a name="indexterm-2586"></a><a name="indexterm-2587"></a><p><a name="indexterm-2588"></a><a name="indexterm-2589"></a><a name="indexterm-2590"></a><a name="indexterm-2591"></a>You can declare security role names used in enterprise bean code using either
the <tt>@DeclareRoles</tt> annotation (preferred) or the <tt>security-role-ref</tt> elements of the deployment descriptor. Declaring security
role names in this way enables you to link these security role names
used in the code to the security roles defined for an assembled application.
In the absence of this linking step, any security role name used in
the code will be assumed to correspond to a security role of
the same name in the assembled application.</p><p>A security role reference, including the name defined by the reference, is scoped
to the component whose bean class contains the <tt>@DeclareRoles</tt> annotation or whose deployment
descriptor element contains the <tt>security-role-ref</tt> deployment descriptor element.</p><p>You can also use the <tt>security-role-ref</tt> elements for those references that were declared
in annotations and you want to have linked to a <tt>security-role</tt> whose name
differs from the reference value. If a security role reference is not linked
to a security role in this way, the container must map the reference
name to the security role of the same name. See <a href="#bnbyt">Linking Security Role References to Security Roles</a> for a
description of how security role references are linked to security roles.</p><p>For an example using each of these methods, read the following sections:</p>
<ul><li><p><a href="#bnbyp">Declaring Security Roles Using Annotations</a></p></li>
<li><p><a href="#bnbyq">Declaring Security Roles Using Deployment Descriptor Elements</a></p></li></ul>


<a name="bnbyp"></a><h5>Declaring Security Roles Using Annotations</h5>
<p>The <tt>@DeclareRoles</tt> annotation is specified on a bean class, where it serves to
declare roles that can be tested by calling <tt>isCallerInRole</tt> from within the
methods of the annotated class.</p><p><a name="indexterm-2592"></a><a name="indexterm-2593"></a>You declare the security roles referenced in the code using the <tt>@DeclareRoles</tt> annotation.
When declaring the name of a role used as a parameter to the
<tt>isCallerInRole(String roleName)</tt> method, the declared name must be the same as the parameter value.
You can optionally provide a description of the named security roles in the
description element of the <tt>@DeclareRoles</tt> annotation.</p><p><a name="indexterm-2594"></a><a name="indexterm-2595"></a>The following code snippet demonstrates the use of the <tt>@DeclareRoles</tt> annotation. In
this example, the <tt>@DeclareRoles</tt> annotation indicates that the enterprise bean <tt>AardvarkPayroll</tt> makes the security
check using <tt>isCallerInRole("payroll")</tt> to verify that the caller is authorized to change salary
data. The security role reference is scoped to the session or entity bean
whose declaration contains the <tt>@DeclareRoles</tt> annotation.</p><pre>@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll {
    @Resource SessionContext ctx;

    public void updateEmployeeInfo(EmplInfo info) {

        oldInfo = ... read from database;

        // The salary field can be changed only by callers
        // who have the security role "payroll"
        if (info.salary != oldInfo.salary &amp;&amp;
            !ctx.isCallerInRole("payroll")) {
                throw new SecurityException(...);
        }
        ...
    }
    ...
}</pre><p>The syntax for declaring more than one role is as shown in
the following example:</p><pre>@DeclareRoles({"Administrator", "Manager", "Employee"})</pre>

<a name="bnbyq"></a><h5>Declaring Security Roles Using Deployment Descriptor Elements</h5>
<a name="indexterm-2596"></a><a name="indexterm-2597"></a>
<hr><p><b>Note - </b><a name="indexterm-2598"></a><a name="indexterm-2599"></a>Any values explicitly specified in the deployment descriptor override any values specified in
annotations. If a value for a method has not been specified in the
deployment descriptor, and a value has been specified for that method by means
of the use of annotations, the value specified in annotations will apply. The
granularity of overriding is on the per-method basis.</p>
<hr>
<p>If the <tt>@DeclareRoles</tt> annotation is not used, you can use the <tt>security-role-ref</tt> elements
of the deployment descriptor to declare the security roles referenced in the code,
as follows:</p>
<ul><li><p><a name="indexterm-2600"></a>Declare the name of the security role using the <tt>role-name</tt> element in the deployment descriptor. The name must be the security role name that is used as a parameter to the <tt>isCallerInRole(String roleName)</tt> method.</p></li>
<li><p>Optionally provide a description of the security role in the <tt>description</tt> element.</p></li></ul>
<p>The following example illustrates how an enterprise bean&rsquo;s references to security roles are
declared in the deployment descriptor. In this example, the deployment descriptor indicates that
the enterprise bean <tt>AardvarkPayroll</tt> makes the security check using <tt>isCallerInRole("payroll")</tt> in its business
method. The security role reference is scoped to the session or entity bean
whose declaration contains the <tt>security-role-ref</tt> element.</p><pre>...
&lt;enterprise-beans>
    ...
    &lt;session>
        &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
        &lt;ejb-class>com.aardvark.payroll.PayrollBean&lt;/ejb-class>
        ...
        &lt;security-role-ref>
            &lt;description>
                This security role should be assigned to the
                employees of the payroll department who are
                allowed to update employees&rsquo; salaries.
            &lt;/description>
            &lt;role-name>payroll&lt;/role-name>
        &lt;/security-role-ref>
        ...
    &lt;/session>
    ...
&lt;/enterprise-beans>
...</pre>

<a name="bnbyr"></a><h4>Defining a Security View of Enterprise Beans</h4>
<a name="indexterm-2601"></a><a name="indexterm-2602"></a><p>You can define a <b>security view</b> of the enterprise beans contained in the <tt>ejb-jar</tt>
file and pass this information along to the deployer. When a security view
is passed on to the deployer, the deployer uses this information to define
method permissions for security roles. If you don&rsquo;t define a security view, the
deployer will have to determine what each business method does to determine which
users are authorized to call each method.</p><p><a name="indexterm-2603"></a><a name="indexterm-2604"></a><a name="indexterm-2605"></a><a name="indexterm-2606"></a><a name="indexterm-2607"></a>A security view consists of a set of <b>security roles</b>, a semantic grouping of
permissions that a given type of users of an application must have to
successfully access the application. Security roles are meant to be logical roles, representing a
type of user. You can define <b>method permissions</b> for each security role. A method
permission is a permission to invoke a specified group of methods of the
enterprise beans&rsquo; business interface, home interface, component interface, and/or web service endpoints. You
can specify an authentication mechanism that will be used to verify the identity
of a user.</p><p>It is important to keep in mind that security roles are used
to define the logical security view of an application. They should not be
confused with the user groups, users, principals, and other concepts that exist in
the Application Server.</p><p>The following sections discuss setting up security roles, authentication mechanisms, and method permissions
that define a security view:</p>
<ul><li><p><a href="#bnbys">Defining Security Roles</a></p></li>
<li><p><a href="#bnbyu">Specifying an Authentication Mechanism</a></p></li>
<li><p><a href="#bnbyv">Specifying Method Permissions</a></p></li></ul>


<a name="bnbys"></a><h5>Defining Security Roles</h5>
<p><a name="indexterm-2608"></a><a name="indexterm-2609"></a><a name="indexterm-2610"></a><a name="indexterm-2611"></a>Use the <tt>@DeclareRoles</tt> and <tt>@RolesAllowed</tt> annotations to define security roles using Java language annotations.
The set of security roles used by the application is the total of
the security roles defined by the security role names used in the <tt>@DeclareRoles</tt>
and <tt>@RolesAllowed</tt> annotations.</p><p><a name="indexterm-2612"></a><a name="indexterm-2613"></a>You can augment the set of security roles defined for the application by
annotations using the <tt>security-role</tt> deployment descriptor element to define security roles, where you
use the <tt>role-name</tt> element to define the name of the security role.</p><p>The following example illustrates how to define security roles in a deployment descriptor:</p><pre>    ...
&lt;assembly-descriptor>
    &lt;security-role>
        &lt;description>
            This role includes the employees of the
            enterprise who are allowed to access the
            employee self-service application. This role
            is allowed only to access his/her own
            information.
        &lt;/description>
        &lt;role-name>employee&lt;/role-name>
    &lt;/security-role>

    &lt;security-role>
        &lt;description>
            This role includes the employees of the human
            resources department. The role is allowed to
             view and update all employee records.
        &lt;/description>
        &lt;role-name>hr-department&lt;/role-name>
    &lt;/security-role>

    &lt;security-role>
        &lt;description>
            This role includes the employees of the payroll
            department. The role is allowed to view and
            update the payroll entry for any employee.
        &lt;/description>
        &lt;role-name>payroll-department&lt;/role-name>
    &lt;/security-role>

    &lt;security-role>
        &lt;description>
            This role should be assigned to the personnel
            authorized to perform administrative functions
            for the employee self-service application.
            This role does not have direct access to
            sensitive employee and payroll information.
        &lt;/description>
        &lt;role-name>admin&lt;/role-name>
    &lt;/security-role>
    ...
&lt;/assembly-descriptor></pre>

<a name="bnbyt"></a><h5>Linking Security Role References to Security Roles</h5>
<a name="indexterm-2614"></a><a name="indexterm-2615"></a><p>The security role references used in the components of the application are linked
to the security roles defined for the application. In the absence of any
explicit linking, a security role reference will be linked to a security role
having the same name.</p><p>You can explicitly link all the security role references declared in the <tt>@DeclareRoles</tt>
annotation or <tt>security-role-ref</tt> elements for a component to the security roles defined by
the use of annotations (as discussed in <a href="#bnbys">Defining Security Roles</a>) and/or in the <tt>security-role</tt> elements.</p><p><a name="indexterm-2616"></a><a name="indexterm-2617"></a><a name="indexterm-2618"></a><a name="indexterm-2619"></a><a name="indexterm-2620"></a>You use the <tt>role-link</tt> element to link each security role reference to a security
role. The value of the <tt>role-link</tt> element must be the name of one
of the security roles defined in a <tt>security-role</tt> element, or by the
<tt>@DeclareRoles</tt> or <tt>@RolesAllowed</tt> annotations (as discussed in <a href="#bnbys">Defining Security Roles</a>). You do not need
to use the <tt>role-link</tt> element to link security role references to security roles
when the <tt>role-name</tt> used in the code is the same as the name
of the <tt>security-role</tt> to which you would be linking.</p><p>The following example illustrates how to link the security role reference name <tt>payroll</tt>
to the security role named <tt>payroll-department</tt>:</p><pre>...
 &lt;enterprise-beans>
     ...
     &lt;session>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;ejb-class>com.aardvark.payroll.PayrollBean&lt;/ejb-class>
         ...
         &lt;security-role-ref>
             &lt;description>
                 This role should be assigned to the
                 employees of the payroll department.
                 Members of this role have access to
                 anyone&rsquo;s payroll record.
                 The role has been linked to the
                 payroll-department role.
             &lt;/description>
             &lt;role-name>payroll&lt;/role-name>
             &lt;role-link>payroll-department&lt;/role-link>
         &lt;/security-role-ref>
         ...
     &lt;/session>
     ...
 &lt;/enterprise-beans>
 ...</pre>

<a name="bnbyu"></a><h5>Specifying an Authentication Mechanism</h5>
<p>Authentications mechanisms are specified in the runtime deployment descriptor. When annotations, such as
the <tt>@RolesAllowed</tt> annotation, are used to protect methods in the enterprise bean, you
can configure the Interoperable Object Reference (IOR) to enable authentication for an enterprise application.
This is accomplished by adding the <tt>&lt;login-config></tt>element to the runtime deployment descriptor, <tt>sun-ejb-jar.xml</tt>.</p><p>You can use the <tt>USERNAME-PASSWORD</tt> authentication method for an enterprise bean. You can
use either the <tt>BASIC</tt> or <tt>CLIENT-CERT</tt> authentication methods for web service endpoints.</p><p>For more information on specifying an authentication mechanism, read <a href="#bnbzf">Configuring IOR Security</a> or <a href="bnbzj.html#bnbzk">Example: Securing an Enterprise Bean</a>.</p>

<a name="bnbyv"></a><h5>Specifying Method Permissions</h5>
<a name="indexterm-2621"></a><a name="indexterm-2622"></a><p>If you have defined security roles for the enterprise beans in the
<tt>ejb-jar</tt> file, you can also specify the methods of the business interface, home
interface, component interface, and/or web service endpoints that each security role is allowed
to invoke.</p><p>You can use annotations and/or the deployment descriptor for this purpose. Refer to
the following sections for more information on specifying method permissions:</p>
<ul><li><p><a href="#bnbyw">Specifying Method Permissions Using Annotations</a></p></li>
<li><p><a href="#bnbyx">Specifying Method Permissions Using Deployment Descriptors</a></p></li></ul>


<a name="bnbyw"></a><h5>Specifying Method Permissions Using Annotations</h5>
<a name="indexterm-2623"></a><a name="indexterm-2624"></a><p>The method permissions for the methods of a bean class can be
specified on the class, the business methods of the class, or both. Method
permissions can be specified on a method of the bean class to override
the method permissions value specified on the entire bean class. The following annotations
are used to specify method permissions:</p>
<ul><li><p><a name="indexterm-2625"></a><a name="indexterm-2626"></a><tt>@RolesAllowed("</tt><i>list-of-roles</i><tt>")</tt></p><p>The value of the <tt>@RolesAllowed</tt> annotation is a list of security role names to be mapped to the security roles that are permitted to execute the specified method or methods. Specifying this annotation on the bean class means that it applies to all applicable business methods of the class.</p></li>
<li><p><a name="indexterm-2627"></a><a name="indexterm-2628"></a><tt>@PermitAll</tt></p><p>The <tt>@PermitAll</tt> annotation specifies that all security roles are permitted to execute the specified method or methods. Specifying this annotation on the bean class means that it applies to all applicable business methods of the class.</p></li>
<li><p><a name="indexterm-2629"></a><a name="indexterm-2630"></a><tt>@DenyAll</tt></p><p>The <tt>@DenyAll</tt> annotation specifies that no security roles are permitted to execute the specified method or methods.</p></li></ul>
<p>The following example code illustrates the use of these annotations:</p><pre>@RolesAllowed("admin")
public class SomeClass {
    public void aMethod () {...}
    public void bMethod () {...}
    ...
}

@Stateless public class MyBean implements A extends SomeClass {

    @RolesAllowed("HR")
    public void aMethod () {...}

    public void cMethod () {...}
    ...
}</pre><p>In this example, assuming <tt>aMethod</tt>, <tt>bMethod</tt>, and <tt>cMethod</tt> are methods of business interface
<tt>A</tt>, the method permissions values of methods <tt>aMethod</tt> and <tt>bMethod</tt> are <tt>@RolesAllowed("HR")</tt> and
<tt>@RolesAllowed("admin")</tt> respectively. The method permissions for method <tt>cMethod</tt> have not been specified.</p><p>To clarify, the annotations are not inherited by the subclass per se, they
apply to methods of the superclass which are inherited by the subclass. Also,
annotations do not apply to CMP entity beans.</p><p>An example that uses annotations to specify method permissions is described in <a href="bnbzj.html#bnbzk">Example: Securing an Enterprise Bean</a>.</p>

<a name="bnbyx"></a><h5>Specifying Method Permissions Using Deployment Descriptors</h5>
<a name="indexterm-2631"></a><a name="indexterm-2632"></a><a name="indexterm-2633"></a>
<hr><p><b>Note - </b>Any values explicitly specified in the deployment descriptor override any values specified in
annotations. If a value for a method has not been specified in the
deployment descriptor, and a value has been specified for that method by means
of the use of annotations, the value specified in annotations will apply. The
granularity of overriding is on the per-method basis.</p>
<hr>
<p>You define the method permissions in the deployment descriptor using the <tt>method-permission</tt> elements,
as discussed below:</p>
<ul><li><p>Each <tt>method-permission</tt> element includes a list of one or more security roles and a list of one or more methods. All the listed security roles are allowed to invoke all the listed methods. Each security role in the list is identified by the <tt>role-name</tt> element. Each method (or set of methods) is identified by the <tt>method</tt> element.</p></li>
<li><p>The method permissions relation is defined as the union of all the method permissions defined in the individual <tt>method-permission</tt> elements.</p></li>
<li><p>A security role or a method can appear in multiple <tt>method-permission</tt> elements.</p></li></ul>
<p>Here is some other useful information about setting method permissions using deployment descriptors:</p>
<ul><li><p><a name="indexterm-2634"></a>You can specify that all roles are permitted to execute one or more specified methods, which, in effect, indicates that the methods should not be checked for authorization prior to invocation by the container. To specify that all roles are permitted, use the <tt>unchecked</tt> element instead of a role name in a method permission.</p><p>If a method permission specifies both the <tt>unchecked</tt> element for a given method and one or more security roles, all roles are permitted for the specified methods.</p></li>
<li><p><a name="indexterm-2635"></a>The <tt>exclude-list</tt> element can be used to indicate the set of methods that should not be called. At deployment time, the deployer will know that no access is permitted to any method contained in this list.</p><p>If a given method is specified in both the <tt>exclude-list</tt> element and in a method permission, the deployer should exclude access to this method.</p></li>
<li><p>It is possible that some methods are not assigned to any security roles nor contained in the <tt>exclude-list</tt> element. In this case, the deployer should assign method permissions for all of the unspecified methods, either by assigning them to security roles, or by marking them as unchecked. If the deployer does not assign method permissions to the unspecified methods, those methods must be treated by the container as unchecked.</p></li>
<li><p>The <tt>method</tt> element uses the <tt>ejb-name</tt>, <tt>method-name</tt>, and <tt>method-params</tt> elements to denote one or more methods of an enterprise bean&rsquo;s business interface, home interface, component interface, and/or web service endpoints.</p></li></ul>
<p><a name="indexterm-2636"></a>There are three legal styles for composing the <tt>method</tt> element:</p>
<ul><li><p>The first style is used for referring to all of the business interface, home interface, component interface, and web service endpoints methods of a specified bean.</p><pre>&lt;method> 
  &lt;ejb-name>EJB_NAME&lt;/ejb-name> 
  &lt;method-name>*&lt;/method-name> 
&lt;/method></pre></li>
<li><p>The second style is used for referring to a specified method of the business interface, home interface, component interface, or web service endpoints methods of the specified enterprise bean. If the enterprise bean contains multiple methods with the same overloaded name, the element of this style refers to all of the methods with the overloaded name.</p><pre>&lt;method> 
  &lt;ejb-name>EJB_NAME&lt;/ejb-name> 
  &lt;method-name>METHOD&lt;/method-name> 
&lt;/method></pre></li>
<li><p>The third style is used for referring to a specified method within a set of methods with an overloaded name. The method must be defined in the business interface, home interface, component interface, or web service endpoints methods of the specified enterprise bean. If there are multiple methods with the same overloaded name, however, this style refers to all of the overloaded methods. All of the parameters are the fully-qualified Java types, for example, <tt>java.lang.String</tt>.</p><pre>&lt;method>
   &lt;ejb-name>EJB_NAME&lt;/ejb-name>
   &lt;method-name>METHOD&lt;/method-name>
   &lt;method-params>
      &lt;method-param>PARAMETER_1&lt;/method-param> 
      &lt;method-param>PARAMETER_2&lt;/method-param> 
   &lt;/method-params>
&lt;/method></pre></li></ul>
<p>The following example illustrates how security roles are assigned method permissions in the
deployment descriptor:</p><pre> ...
 &lt;method-permission>
     &lt;role-name>employee&lt;/role-name>
     &lt;method>
         &lt;ejb-name>EmployeeService&lt;/ejb-name>
         &lt;method-name>*&lt;/method-name>
     &lt;/method>
 &lt;/method-permission>

 &lt;method-permission>
     &lt;role-name>employee&lt;/role-name>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>findByPrimaryKey&lt;/method-name>
     &lt;/method>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>getEmployeeInfo&lt;/method-name>
     &lt;/method>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>updateEmployeeInfo&lt;/method-name>
     &lt;/method>
 &lt;/method-permission>

 &lt;method-permission>
     &lt;role-name>payroll-department&lt;/role-name>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>findByPrimaryKey&lt;/method-name>
     &lt;/method>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>getEmployeeInfo&lt;/method-name>
     &lt;/method>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>updateEmployeeInfo&lt;/method-name>
     &lt;/method>
     &lt;method>
         &lt;ejb-name>AardvarkPayroll&lt;/ejb-name>
         &lt;method-name>updateSalary&lt;/method-name>
     &lt;/method>
 &lt;/method-permission>

 &lt;method-permission>
     &lt;role-name>admin&lt;/role-name>
     &lt;method>
         &lt;ejb-name>EmployeeServiceAdmin&lt;/ejb-name>
         &lt;method-name>*&lt;/method-name>
     &lt;/method>
 &lt;/method-permission>
 ...</pre>

<a name="bnbyy"></a><h5>Mapping Security Roles to Application Server Groups</h5>
<p>The Application Server assigns users to <b>principals</b> or <b>groups</b>, rather than to
security roles. When you are developing a Java EE application, you don&rsquo;t need
to know what categories of users have been defined for the realm in
which the application will be run. In the Java EE platform, the security
architecture provides a mechanism for mapping the roles defined in the application to
the users or groups defined in the runtime realm.</p><p>To map a role name permitted by the application or module to
principals (users) and groups defined on the server, use the <tt>security-role-mapping</tt> element in the
runtime deployment descriptor (<tt>sun-application.xml</tt>, <tt>sun-web.xml</tt>, or <tt>sun-ejb-jar.xml</tt>) file. The entry needs to declare
a mapping between a security role used in the application and one or
more groups or principals defined for the applicable realm of the Application
Server. An example for the <tt>sun-application.xml</tt> file is shown below:</p><pre>&lt;sun-application>
    &lt;security-role-mapping>
        &lt;role-name>CEO&lt;/role-name>
        &lt;principal-name>jschwartz&lt;/principal-name>
    &lt;/security-role-mapping>
    &lt;security-role-mapping>
        &lt;role-name>ADMIN&lt;/role-name>
        &lt;group-name>directors&lt;/group-name>
    &lt;/security-role-mapping>
&lt;/sun-application></pre><p>The role name can be mapped to either a specific principal (user),
a group, or both. The principal or group names referenced must be valid
principals or groups in the current default realm of the Application Server. The
<tt>role-name</tt> in this example must exactly match the <tt>role-name</tt> in the <tt>security-role</tt> element
of the corresponding <tt>web.xml</tt> file or the role name defined in the
<tt>@DeclareRoles</tt> or <tt>@RolesAllowed</tt> annotations.</p><p>Sometimes the role names used in the application are the same as
the group names defined on the Application Server. Under these circumstances, you can enable
a default principal-to-role mapping on the Application Server using the Admin Console. To
enable the default principal-to-role-mapping, follow these steps:</p>
<ol><li><p>Start the Application Server, then the Admin Console.</p></li>
<li><p>Expand the Configuration node.</p></li>
<li><p>Select the Security node.</p></li>
<li><p>On the Security page, check the Enabled box beside Default Principal to Role Mapping.</p></li></ol>
<p>For an enterprise application, you can specify the security role mapping at the
application layer, in <tt>sun-application.xml</tt>, or at the module layer, in <tt>sun-ejb-jar.xml</tt>. When specified at
the application layer, the role mapping applies to all contained modules and overrides
same-named role mappings at the module layer. The assembler is responsible for reconciling
the module-specific role mappings to yield one effective mapping for the application.</p><p>Both example applications demonstrate security role mapping. For more information, see <a href="bnbzj.html#bnbzk">Example: Securing an Enterprise Bean</a> and
<a href="bnbzj.html#bncaa">Example: Using the <tt>isCallerInRole</tt> and <tt>getCallerPrincipal</tt> Methods</a>.</p>

<a name="bnbyz"></a><h5>Propagating Security Identity</h5>
<a name="indexterm-2637"></a><a name="indexterm-2638"></a><a name="indexterm-2639"></a><a name="indexterm-2640"></a><a name="indexterm-2641"></a><p>You can specify whether a caller&rsquo;s security identity should be used for the
execution of specified methods of an enterprise bean, or whether a specific run-as
identity should be used.</p><p><a href="#bnbza">Figure&nbsp;29-2</a> illustrates this concept.</p><a name="bnbza"></a><h6>Figure&nbsp;29-2 Security Identity Propagation</h6><img src="figures/security-idPropag.gif" alt="Diagram of security identity propagation from client to intermediate container to target container"></img><p>In this illustration, an application client is making a call to an
enterprise bean method in one EJB container. This enterprise bean method, in turn,
makes a call to an enterprise bean method in another container. The security
identity during the first call is the identity of the caller. The security
identity during the second call can be any of the following options:</p>
<ul><li><p>By default, the identity of the caller of the intermediate component is propagated to the target enterprise bean. This technique is used when the target container trusts the intermediate container.</p></li>
<li><p><a name="indexterm-2642"></a>A specific identity is propagated to the target enterprise bean. This technique is used when the target container expects access using a specific identity.</p><p>To propagate an identity to the target enterprise bean, configure a run-as identity for the bean as discussed in <a href="#bnbzb">Configuring a Component's Propagated Security Identity</a>.</p><p>Establishing a run-as identity for an enterprise bean does not affect the identities of its callers, which are the identities tested for permission to access the methods of the enterprise bean. The run-as identity establishes the identity that the enterprise bean will use when it makes calls.</p><p>The run-as identity applies to the enterprise bean as a whole, including all the methods of the enterprise bean&rsquo;s business interface, home interface, component interface, and web service endpoint interfaces, the message listener methods of a message-driven bean, the time-out callback method of an enterprise bean, and all internal methods of the bean that might be called in turn.</p></li></ul>


<a name="bnbzb"></a><h5>Configuring a Component&rsquo;s Propagated Security Identity</h5>
<p>You can configure an enterprise bean&rsquo;s run-as, or propagated, security identity using either
of the following:</p>
<ul><li><p><a name="indexterm-2643"></a><a name="indexterm-2644"></a><a name="indexterm-2645"></a>The <tt>@RunAs</tt> annotation</p><p>The following example illustrates the definition of a run-as identity using annotations:</p><pre>@RunAs("admin")
@Stateless public class EmployeeServiceBean 
    implements EmployeeService { 
       ...
}</pre></li>
<li><p><a name="indexterm-2646"></a>The <tt>role-name</tt> element of the <tt>run-as</tt> application deployment descriptor element (<tt>web.xml</tt>, <tt>ejb-jar.xml</tt>)</p><p>The following example illustrates the definition of a <tt>run-as</tt> identity using deployment descriptor elements:</p><pre>...
&lt;enterprise-beans> 
  ... 
  &lt;session> 
    &lt;ejb-name>EmployeeService&lt;/ejb-name> 
    ... 
    &lt;security-identity> 
      &lt;run-as> 
        &lt;role-name>admin&lt;/role-name> 
      &lt;/run-as> 
    &lt;/security-identity> 
    ... 
  &lt;/session> 
  ...
&lt;/enterprise-beans>
...</pre></li></ul>
<p><a name="indexterm-2647"></a>Alternately, you can use the <tt>use-caller-identity</tt> element to indicate that you want to
use the identity of the original caller, as shown in the code below:</p><pre>&lt;security-identity>
    &lt;use-caller-identity />
&lt;/security-identity></pre><p>You must explicitly specify the run-as role name mapping to a given principal
in <tt>sun-web.xml</tt> or <tt>sun-ejb-jar.xml</tt> if the given roles associate to more than one
user principal.</p><p>More detail about the elements contained in deployment descriptors is available in the
<a href="http://docs.sun.com/doc/819-3673"><i>Sun Java System Application Server 9.1 Application Deployment Guide</i></a>.</p><p>In either case, you will have to map the run-as role name
to a given principal defined on the Application Server if the given roles
associate to more than one user principal. Mapping roles to principals is described
in <a href="#bnbyy">Mapping Security Roles to Application Server Groups</a>.</p>

<a name="bnbzc"></a><h5>Trust between Containers</h5>
<a name="indexterm-2648"></a><a name="indexterm-2649"></a><p>When an enterprise bean is designed so that either the original caller identity
or a designated identity is used to call a target bean, the
target bean will receive the propagated identity only; it will not receive any
authentication data.</p><p>There is no way for the target container to authenticate the propagated security
identity. However, because the security identity is used in authorization checks (for example,
method permissions or with the <tt>isCallerInRole()</tt> method), it is vitally important that the
security identity be authentic. Because there is no authentication data available to authenticate
the propagated identity, the target must trust that the calling container has propagated
an authenticated security identity.</p><p>By default, the Application Server is configured to trust identities that are propagated
from different containers. Therefore, there are no special steps that you need to
take to set up a trust relationship.</p>

<a name="bnbzd"></a><h4>Using Enterprise Bean Security Annotations</h4>
<a name="indexterm-2650"></a><a name="indexterm-2651"></a><p>Annotations are used in code to relay information to the deployer about security
and other aspects of the application. Specifying this information in annotations or in
the deployment descriptor helps the deployer set up the appropriate security policy for
the enterprise bean application.</p><p>Any values explicitly specified in the deployment descriptor override any values specified in
annotations. If a value for a method has not been specified in the
deployment descriptor, and a value has been specified for that method by means
of the use of annotations, the value specified in annotations will apply. The
granularity of overriding is on the per-method basis.</p><p>The following is a listing of annotations that address security, can be used
in an enterprise bean, and are discussed in this tutorial:</p>
<ul><li><p><a name="indexterm-2652"></a>The <tt>@DeclareRoles</tt> annotation declares each security role referenced in the code. Use of this annotation is discussed in <a href="#bnbyp">Declaring Security Roles Using Annotations</a>.</p></li>
<li><p><a name="indexterm-2653"></a><a name="indexterm-2654"></a><a name="indexterm-2655"></a>The <tt>@RolesAllowed</tt>, <tt>@PermitAll</tt>, and <tt>@DenyAll</tt> annotations are used to specify method permissions. Use of these annotations is discussed in <a href="#bnbyw">Specifying Method Permissions Using Annotations</a>.</p></li>
<li><p><a name="indexterm-2656"></a>The <tt>@RunAs</tt> metadata annotation is used to configure a component&rsquo;s propagated security identity. Use of this annotation is discussed in <a href="#bnbzb">Configuring a Component's Propagated Security Identity</a>.</p></li></ul>


<a name="bnbze"></a><h4>Using Enterprise Bean Security Deployment Descriptor Elements</h4>
<a name="indexterm-2657"></a><a name="indexterm-2658"></a><p>Enterprise JavaBeans components use an EJB deployment descriptor that must be named <tt>META-INF/ejb-jar.xml</tt>
and must be contained in the EJB JAR file. The role of the
deployment descriptor is to relay information to the deployer about security and other
aspects of the application. Specifying this information in annotations or in the deployment
descriptor helps the deployer set up the appropriate security policy for the enterprise
bean application. More detail about the elements contained in deployment descriptors is available in
the <a href="http://docs.sun.com/doc/819-3673"><i>Sun Java System Application Server 9.1 Application Deployment Guide</i></a>.</p>
<hr><p><b>Note - </b>Using annotations is the recommended method for adding security to enterprise bean applications.</p>
<hr>
<p>Any values explicitly specified in the deployment descriptor override any values specified in
annotations. If a value for a method has not been specified in the
deployment descriptor, and a value has been specified for that method by means
of the use of annotations, the value specified in annotations will apply. The
granularity of overriding is on the per-method basis.</p><p>The following is a listing of deployment descriptor elements that address security, can
be used in an enterprise bean, and are discussed in this tutorial:</p>
<ul><li><p><a name="indexterm-2659"></a>The <tt>security-role-ref</tt> element declares each security role referenced in the code. Use of this element is discussed in <a href="#bnbyq">Declaring Security Roles Using Deployment Descriptor Elements</a>.</p></li>
<li><p><a name="indexterm-2660"></a>The <tt>security-role</tt> element defines broad categories of users, and is used to provide access to protected methods. Use of this element is discussed in <a href="#bnbys">Defining Security Roles</a>.</p></li>
<li><p><a name="indexterm-2661"></a>The <tt>method-permission</tt> element is used to specify method permissions. Use of these elements is discussed in <a href="#bnbyx">Specifying Method Permissions Using Deployment Descriptors</a>.</p></li>
<li><p><a name="indexterm-2662"></a>The <tt>run-as</tt> element is used to configure a component&rsquo;s propagated security identity. Use of this element is discussed in <a href="#bnbzb">Configuring a Component's Propagated Security Identity</a>.</p></li></ul>
<p>The schema for <tt>ejb-jar</tt> deployment descriptors can be found in section 18.5, <i>Deployment Descriptor XML Schema</i>, in
the <i>EJB 3.0 Specification</i> (JSR-220) at <a href="http://jcp.org/en/jsr/detail?id=220">http://jcp.org/en/jsr/detail?id=220</a>.</p>

<a name="bnbzf"></a><h4>Configuring IOR Security</h4>
<a name="indexterm-2663"></a><a name="indexterm-2664"></a><a name="indexterm-2665"></a><a name="indexterm-2666"></a><a name="indexterm-2667"></a><a name="indexterm-2668"></a><a name="indexterm-2669"></a><p>The EJB interoperability protocol is based on Internet Inter-ORB Protocol (IIOP/GIOP 1.2) and
the Common Secure Interoperability version 2 (CSIv2) CORBA Secure Interoperability specification.</p><p>Enterprise beans that are deployed in one vendor&rsquo;s server product are often accessed
from Java EE client components that are deployed in another vendor&rsquo;s product. CSIv2,
a CORBA/IIOP-based standard interoperability protocol, addresses this situation by providing authentication, protection of integrity
and confidentiality, and principal propagation for invocations on enterprise beans, where the invocations
take place over an enterprise&rsquo;s intranet. CSIv2 configuration settings are specified in the
Interoperable Object Reference (IOR) of the target enterprise bean. IOR configurations are defined in
Chapter 24 of the CORBA/IIOP specification, <i>Secure Interoperability</i>. This chapter can be downloaded
from <a href="http://www.omg.org/cgi-bin/doc?formal/02-06-60">http://www.omg.org/cgi-bin/doc?formal/02-06-60</a>.</p><p>The EJB interoperability protocol is defined in Chapter 14, <i>Support for Distribution and Interoperability</i>, of the
EJB specification, which can be downloaded from <a href="http://jcp.org/en/jsr/detail?id=220">http://jcp.org/en/jsr/detail?id=220</a>.</p><p>Based on application requirements, IORs are configured in vendor-specific XML files, such as
<tt>sun-ejb-jar.xml</tt>, instead of in standard application deployment descriptor files, such as <tt>ejb-jar.xml</tt>.</p><p>For a Java EE application, IOR configurations are specified in Sun-specific xml files,
for example, <tt>sun-ejb-jar_2_1-1.dtd</tt>. The <tt>ior-security-config</tt> element describes the security configuration information for the
IOR. A description of some of the major subelements is provided below.</p>
<ul><li><p><tt>transport-config</tt></p><p>This is the root element for security between the endpoints. It contains the following elements:</p>
<ul><li><p><tt>integrity</tt>: This element specifies whether the target supports integrity-protected messages for transport. The values are <tt>NONE</tt>, <tt>SUPPORTED</tt>, or <tt>REQUIRED</tt>.</p></li>
<li><p><tt>confidentiality</tt>: This element specifies whether the target supports privacy-protected messages (SSL) for transport. The values are <tt>NONE</tt>, <tt>SUPPORTED</tt>, or <tt>REQUIRED</tt>.</p></li>
<li><p><tt>establish-trust-in-target</tt>: This element specifies whether or not the target component is capable of authenticating to a client for transport. It is used for mutual authentication (to validate the server&rsquo;s identity). The values are <tt>NONE</tt>, <tt>SUPPORTED</tt>, or <tt>REQUIRED</tt>.</p></li>
<li><p><tt>establish-trust-in-client</tt>: This element specifies whether or not the target component is capable of authenticating a client for transport (target asks the client to authenticate itself). The values are <tt>NONE</tt>, <tt>SUPPORTED</tt>, or <tt>REQUIRED</tt>.</p></li></ul>
</li>
<li><p><tt>as-context</tt></p><p>This is the element that describes the authentication mechanism (CSIv2 authentication service) that will be used to authenticate the client. If specified, it will be the username-password mechanism.</p><p>In the Duke&rsquo;s Bank example, the <tt>as-context</tt> setting is used to require client authentication (with user name and password) when access to protected methods in the <tt>AccountControllerBean</tt> and <tt>CustomerControllerBean</tt> components is attempted.</p><p>The <tt>as-context</tt> element contains the following elements:</p>
<ul><li><p><tt>required</tt>: This element specifies whether the authentication method specified is required to be used for client authentication. Setting this field to <tt>true</tt> indicates that the authentication method specified is required. Setting this field to <tt>false</tt> indicates that the method authentication is not required. The element value is either <tt>true</tt> or <tt>false</tt>.</p></li>
<li><p><tt>auth-method</tt>: This element specifies the authentication method. The only supported value is <tt>USERNAME_PASSWORD</tt>.</p></li>
<li><p><tt>realm</tt>: This element specifies the realm in which the user is authenticated. Must be a valid realm that is registered in a server configuration.</p></li></ul>
</li>
<li><p><tt>sas-context</tt></p><p>This element is related to the CSIv2 security attribute service. It describes the <tt>sas-context</tt> fields.</p><p>In the Duke&rsquo;s Bank example, the <tt>sas-context</tt> setting is set to <tt>Supported</tt> for the <tt>AccountBean</tt>, <tt>CustomerBean</tt>, and <tt>TxBean</tt> components, indicating that these target components will accept propagated caller identities.</p><p>The <tt>sas-context</tt> element contains the <tt>caller-propagation</tt> subelement. This element indicates if the target will accept propagated caller identities. The values are <tt>NONE</tt> or <tt>SUPPORTED</tt>.</p></li></ul>
<p>The following is an example that defines security for an IOR:</p><pre>&lt;sun-ejb-jar>
    &lt;enterprise-beans>
        &lt;unique-id>1&lt;/unique-id>
        &lt;ejb>
            &lt;ejb-name>HelloWorld&lt;/ejb-name>
            &lt;jndi-name>HelloWorld&lt;/jndi-name>
            &lt;ior-security-config>
                &lt;transport-config>
                    &lt;integrity>NONE&lt;/integrity>
                    &lt;confidentiality>NONE&lt;/confidentiality>
                    &lt;establish-trust-in-target>
                        NONE
                    &lt;/establish-trust-in-target>
                    &lt;establish-trust-in-client>
                        NONE
                    &lt;/establish-trust-in-client>
                &lt;/transport-config>
                &lt;as-context>
                    &lt;auth-method>USERNAME_PASSWORD&lt;/auth-method>
                    &lt;realm>default&lt;/realm>
                    &lt;required>true&lt;/required>
                &lt;/as-context>
                &lt;sas-context>
                    &lt;caller-propagation>NONE&lt;/caller-propagation>
                &lt;/sas-context>
            &lt;/ior-security-config>
            &lt;webservice-endpoint>
                &lt;port-component-name>HelloIF&lt;/port-component-name>
                &lt;endpoint-address-uri>
                    service/HelloWorld
                &lt;/endpoint-address-uri>
                &lt;login-config>
                    &lt;auth-method>BASIC&lt;/auth-method>
                &lt;/login-config>
            &lt;/webservice-endpoint>
        &lt;/ejb>
    &lt;/enterprise-beans>
&lt;/sun-ejb-jar></pre>

<a name="bnbzg"></a><h4>Deploying Secure Enterprise Beans</h4>
<a name="indexterm-2670"></a><p>The deployer is responsible for ensuring that an assembled application is secure after
it has been deployed in the target operational environment. If a security view
(security annotations and/or a deployment descriptor) has been provided to the deployer, the
security view is mapped to the mechanisms and policies used by the security
domain in the target operational environment, which in this case is the Application
Server. If no security view is provided, the deployer must set up the
appropriate security policy for the enterprise bean application.</p><p>Deployment information is specific to a web or application server. Please read the
<a href="http://docs.sun.com/doc/819-3673"><i>Sun Java System Application Server 9.1 Application Deployment Guide</i></a> for more information on deploying enterprise beans.</p>

<a name="bnbzh"></a><h5>Accepting Unauthenticated Users</h5>
<a name="indexterm-2671"></a><a name="indexterm-2672"></a><p>Web applications accept unauthenticated web clients and allow these clients to make calls
to the EJB container. The EJB specification requires a security credential for accessing
EJB methods. Typically, the credential will be that of a generic unauthenticated user.
The way you specify this credential is implementation-specific.</p><p>In the Application Server, you must specify the name and password that
an unauthenticated user will use to log in by modifying the Application Server
using the Admin Console:</p>
<ol><li><p>Start the Application Server, then the Admin Console.</p></li>
<li><p>Expand the Configuration node.</p></li>
<li><p>Select the Security node.</p></li>
<li><p>On the Security page, set the Default Principal and Default Principal Password values.</p></li></ol>


<a name="bnbzi"></a><h5>Accessing Unprotected Enterprise Beans</h5>
<a name="indexterm-2673"></a><a name="indexterm-2674"></a><a name="indexterm-2675"></a><p>If the deployer has granted full access to a method, any user
or group can invoke the method. Conversely, the deployer can deny access to
a method.</p><p>To modify which role can be used in applications to grant authorization to
anyone, specify a value for Anonymous Role. To set the Anonymous Role
field, follow these steps:</p>
<ol><li><p>Start the Application Server, then the Admin Console.</p></li>
<li><p>Expand the Configuration node.</p></li>
<li><p>Select the Security node.</p></li>
<li><p>On the Security page, specify the Anonymous Role value.</p></li></ol>

         </div>
         <div class="navigation">
             <a href="bnbyk.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnbzj.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

